…e_cache

Addresses P1 and P2 findings from code review:
- Raises ConfigurationError if options.cache is used alongside sources.
- Validates tools as dictionaries before creation in Gemini provider.

Updates caching.md to not pass sources alongside a cache handle, which is now explicitly rejected by ConfigurationError.

…dles

Move create_cache implementation from __init__.py into cache.py
(create_cache_impl, _resolve_file_parts, module-level _registry),
leaving __init__.create_cache as a thin provider-lifecycle wrapper.

Shift cache-handle conflict validation (provider/model mismatch,
system_instruction/tools/tool_choice/sources conflicts) from
execute_plan() into build_plan() so errors surface at planning time
before any network I/O. Retain a single runtime persistent_cache
capability check in execute_plan() as a safety net for hand-built
handles.

The new _resolve_file_parts memoizes uploads by (file_path, mime_type)
to avoid duplicate uploads for repeated file sources within a single
create_cache() call.

…alls

Move _resolve_file_parts() into the single-flight work function inside
get_or_create_cache() so concurrent callers for the same cache key share
both uploads and cache creation.  Previously uploads ran before the
single-flight boundary, causing duplicate uploads when two coroutines
raced past the registry miss.

get_or_create_cache() now accepts raw_parts (unresolved placeholders)
and resolves them inside _work().  Add
test_cache_single_flight_deduplicates_file_uploads to verify
upload_calls==1 and cache_calls==1 under concurrency.

Include api_key in compute_cache_key() so different credentials for the
same provider/model produce distinct cache entries.  Prevents silent
cross-account handle reuse in multi-tenant or multi-key scenarios.

Also fix the create_cache() docstring example which referenced an
undefined `config` variable (now uses `cfg` consistently).

- Validate tool items are dicts in create_cache_impl before uploads,
  preventing wasted file uploads on invalid input
- Validate system_instruction type at the API boundary, converting a
  raw TypeError into a ConfigurationError with hint
- Pass through ConfigurationError in wrap_provider_error instead of
  re-wrapping as CacheError

An expired CacheHandle passed via Options(cache=handle) was silently
accepted, leading to a cryptic provider error. Now caught eagerly with
a clear ConfigurationError before any network I/O.